@cloudflare/workers-types

What is @cloudflare/workers-types?

@cloudflare/workers-types provides TypeScript type definitions for Cloudflare Workers, enabling developers to write type-safe code for Cloudflare's serverless platform.

What are @cloudflare/workers-types's main functionalities?

FetchEvent

The FetchEvent interface represents the event that is fired when a Fetch request is made. This allows you to intercept and handle HTTP requests.

addEventListener('fetch', (event) => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request: Request): Promise<Response> {
  return new Response('Hello, world!');
}

KVNamespace

KVNamespace provides type definitions for Cloudflare Workers KV, a key-value storage system. This allows you to interact with KV storage in a type-safe manner.

declare const MY_KV_NAMESPACE: KVNamespace;

async function handleRequest(request: Request): Promise<Response> {
  const value = await MY_KV_NAMESPACE.get('my-key');
  return new Response(value || 'Key not found');
}

DurableObjectNamespace

DurableObjectNamespace provides type definitions for Durable Objects, which are stateful objects that can be used to manage state across multiple requests.

declare const MY_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;

class MyDurableObject {
  state: DurableObjectState;
  constructor(state: DurableObjectState) {
    this.state = state;
  }

  async fetch(request: Request): Promise<Response> {
    return new Response('Durable Object response');
  }
}

addEventListener('fetch', (event) => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request: Request): Promise<Response> {
  const id = MY_DURABLE_OBJECT_NAMESPACE.idFromName('object-name');
  const stub = MY_DURABLE_OBJECT_NAMESPACE.get(id);
  return stub.fetch(request);
}

Other packages similar to @cloudflare/workers-types

@types/aws-lambda

@types/aws-lambda provides TypeScript type definitions for AWS Lambda, another serverless computing platform. While it offers type safety for AWS Lambda functions, it does not cover Cloudflare-specific features.

@types/express

@types/express provides TypeScript type definitions for Express.js, a web application framework for Node.js. While it helps in building server-side applications, it does not offer the serverless and edge computing capabilities of Cloudflare Workers.

README

Cloudflare Workers Types

:stop_sign: This repository was for @cloudflare/workers-types versions ≤ 3 and is no longer maintained.

Since version 4, types are automatically generated from and in the workerd repository.

Find the new README here and the new auto-generation scripts here.

Please raise issues with type definitions in the workerd repository, tagging @cloudflare/workers-types in your report.

---

Legacy Documentation

Install

npm install -D @cloudflare/workers-types
-- Or
yarn add -D @cloudflare/workers-types

Usage

:warning: If you're upgrading from version 2, make sure to remove webworker from the lib array in your tsconfig.json. These types are now included in @cloudflare/workers-types.

The following is a minimal tsconfig.json for use alongside this package:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "lib": ["ES2020"],
    "types": ["@cloudflare/workers-types"]
  }
}

Using bindings

It's recommended that you create an ambient type file for any bindings your Worker uses. Create a file named bindings.d.ts in your src directory:

bindings.d.ts

export {};

declare global {
  const MY_ENV_VAR: string;
  const MY_SECRET: string;
  const myKVNamespace: KVNamespace;
}

Auto-Generation

Types are automatically generated from the Workers runtime's source code on every release. However, these generated types don't include any generics or overloads, so to improve ergonomics, some of them are overridden.

The overrides directory contains partial TypeScript declarations. If an override has a different type classification than its generated counterpart – for example, an interface is declared to override a generated class definition – then the override is used instead of the generated output. However, if they're the same type classification (e.g. both the override and the generated output are using class), then their member properties are merged:

• Members in the override but not in the generated type are included in the output
• If a member in the override has the same name as one in the generated type, the generated one is removed from the output, and the override is included instead
• If the member is declared type never in the override, it is removed from the output

If a named type override is declared as a type alias to never, that named type is removed from the output.

JSDoc comments from overrides will also be copied over to the output.

Comment overrides can also be written in Markdown. The docs directory contains these overrides. 2^nd level headings are the names of top level declarations (e.g. ## `KVNamespace`), 3^rd level headings are for member names (e.g. ### `KVNamespace#put`), and 4^th level headings correspond to JSDoc sections for members:

• #### Parameters: a list with parameters of the form - `param`: param description, these will be formatted as @param tags
• #### Returns: contents will be copied as-is to the @returns tag
• #### Examples: fenced code blocks with the language set to js, ts, javascript or typescript will be copied to @example tags